Klarity General Architecture

Expectation description of specific element of design of Klarity.

Architecture constraint

Web application

Klarity Dashboard shall be used as a progressive web application (PWA)

ℹ PWA is not expected for MVP but architecture choice must be compatible.

Storage strategy

• a local cache storage shall be integrate in library to maximize offline functionality and/or latency in processing.
• local shall store file in user space to preserve access right

Modularity strategy

➡ Linked to discussion #60

Klarity shall be built around a modularity strategy articulated between three concept :

1. Bundle
2. Extension
3. Plugin

This speeds up execution by optimizing the size of instances in relation to needs. This simplify update as only the updated module are updated.

Modules are used to control different functionalities of Klarity Dashboard :

1. The display of an artefact
2. The actions available to a user

Bundle

The web application is splitted into binary packages known as "bundle".

• one for klarity core elements
• one for external dependancies
• one (or multiple) for extension

Bundles are generated at build time.

Extension

An extension is an element of code that can evolve independantly from the core elements of Klarity. It has it's own package, version and configuration and might be developed by anyone outside of Klarity main team.

Extension can be integrated in the application :

• during build time, integrating an extension bundle.
• during deploy time.

ℹ Deployement time extension is not expected for MVP but architecture choice must be compatible.

Plugin

A plugin is an extension that can be integrated at runtime.

ℹ Plugin management is not expected for MVP but architecture choice must be compatible.

---

Extension for metrics - technical elements

• [ ] KD Core has a base factory component and an interface that will be used to develop a module,
• [ ] A render component is a front-end component that handle the display of an artefact,
• [ ] A module might implement new artefacts types,
• [ ] A module is implemented in a dedicated repository,
• [ ] When loading a module, it will register which metric types it implements to the factory component : custom_metric_type and identifies which render component it wants to use.
  • if the metric type already exists an error will be generated at build time.
  • if a metric type is registered without a render component an error will be generated at build time.
• [ ] Base metrics type integrated in Klarity native build are handled as bundle/extensions.
• [ ] All module share a common interface to interact with the core
  • [ ] a list of methods call to interact with core.
  • [ ] method prototype will be common to all modules.
  • [ ] A dedicated behaviour shall be specify regarding component.
  • [ ] This interface must be as simple as possible.

Figma extension interface can be used as general inspiration or for a better understanding of the mecanisms.

ℹ For the MVP the bundle split can be as it follow :

• Dependencies bundle
• Core layout management
• Group of native modules
• A sample of specific extensions

ℹ Product : Version of these elements must be cached by front and load >only if version change.

---

Extension for action - technical elements

Extension, Action & Capability

An extension (or a plugin) specifies :

• the behavior (action) of the application.
  • for instance, an extension might provide a "poke user" next to users' username. Clicking this button would send a notification to the with a link to the discussion where the pake have been issued.
    This is the behavior of the application generated by the action "poke user" defined in an extension.
• the associated capability nature a user must hold (through one of his roles).
  • For instance, the extension will declare a capability nature "_poke" required to proceed with the poking action function.

Both elements are declared in the extension. It means that if the extension is removed both Action & Capability are no more either.

PCIV & SubCapability

In the PCIV configuration we have a reference to the capability suffix declared in the extension implementation, this reference is associated to a prefix. The association of the prefix and the suffix defines a SubCapability which is a capability that can only be done on the Metric Group it is declared.

• This SubCapability will then be used by roles. If a role has this SubCapability in the on-going stage then all users with this role will be able to proceed with the Action initially declared in the extension.

Role

Role is a matrix of SubCapabilities and Stage.

ℹ For the MVP this matrix will be hard coded as already know the subcapabilities and how we want to associate them with roles and stages (we still have to provide a table)

ℹ For the product version the table for each role will be generated at built or deploy time and a project leader (or someone with the rights) much check the cell to allow user to achieve each subcapbility for each stage. Sample/template of rights will be provided to simplify this step.

ℹ It means the project leader must understand/know the action behind each prefix_suffix

ℹ It means the list can be updated if the configuration.json file is updated > the project lead must then update the table.

User

Each user has one to multiple role, which grant him the associated SubCapabilities and therefore, actions. This assignment is done through the graphic user interface with a page with user adminitration and role assignment functionalities.

Class Diagram

1. action belongs to the extension
2. capability belongs to extension and is associated to an action
3. PCIV configuration file declare subcapabilities by associating prefixes to an existing capability suffix. Yet it might not use any of the capability of an extension.
   It can declare "n" SubCapabilities (for a same action or for different actions)
4. SubCapability belongs to the PCIV configuration file, if this PCIV is destroyed there is no more SubCapability
5. Role has SubCapability active or inactive for each stage. Matrix creation must still be defined.
6. User has one to multiple role.

---

Front-end

Klarity Dashboard is a reactive single page application.

Routing & Navigation

Routing objectives

• Define routing strategy between the different dashboards
• Define the switch method between dahsboards

Routing parameter to take into account

• company name : <company_name>.safenai.io
• stage : (scoping, dev, operation)
• abstraction level : (Company, Project, InDepth )
  • ljv.safenai.io/operation/project/polemploi
  • ljv.safenai.io/scoping/compagny
  • ljv.safenai.io/scoping/indepth/polemploi/robustness

ℹ To be updated with #4 proposition

Development constraint :

• Navigation functionalities shall allow swift navigation between previous and next dashboards
• User must be able to open multiple tab, and to pin some, to facilitate his navigation.
• As architecture enable minimal interaction with back-end (cache, and notification of version change) navigation has to be fast and swift.
• Add link to the routing specification in KD documentation.

ℹ Tab management is not expected for MVP, yet architecture must take it into account for product version.

Security

Authentication

Authentication designates how we get an access token using a username.

• external authentication
• right management

Autorisation

Autorisation designates the capability of a user to proceed with an action. Actions are associated to capabilities, capabilities are associated to roles and finally, user holds one to multiple roles.

Request and cache management

MVP : return the list of couple active (version-project) (maximum 3 version per project)

FULL_VERSION : Push request to registered front will push version change to the front.

On reception of this request to collect new version might be perform on version change compared to cache version available

exemple of answer to be challenged during API design TODO : name of metrics are subject to change, a first list for POC, [see metrics)[../../artefacts/metrics.md] for more informations. { "name" : "toto", "version" : "1.0.0", "stage" : "scoping", "metrics" : { "ODD" : { "ODD_REQ_VALIDATED_RATIO" : 0.33, "ODD_REQ_COUNT" : 5 }, "ETHIC_CHECK : { "ETHIC_REQ_VALIDATED_RATIO" : 0.55, "ETHIC_REQ_COUNT" : 156 }, ... } }

mutable metrics

FULL_VERSION : Front might register to update on specific mutable metrics

As described most data managed by karity are on purpose immutable per version enabling a large usage of cache, and offline work capability.

Most of the interaction shall be available offline, pushed to server when back online. Exemple : writing of comment on existing metrics / requirement shall be available offline, update performed when back online.

Immutable data

Immutable (default value, only change on project version change)

Mutable data

The only mutable information for a specific project version are Validity status, ( and TBC specific metrics for operation)

Data management

Ownership of data between gitab and Klarity

• All metrics configuration / definition are manage in gitlab and pushed to klarity MVP : configuration can be code injected in klarity component. MVP : these data are immutable per version no need to store them in Database

  FULL_VERSION : interface upgrade between KM and KD to limit data duplication.

• All metrics values are manage by KM and pushed to KD MVP : depending on metrics, it can be - directly inside the PCIV - in a dedicated object reference inside the payload (time_series and/or images (S3 object)) MVP : these data are immutable per version non need to store them in Database MVP : a graph might be build to link these data in order to request the see memgraph.com or no database and direct usage of json files in a directory

• Project status :

  • compute and manage by klarity see Project status MVP : a relational database can be used, but can also be computed

• Validity status :

  • manage by klarity base on user action
  • provide accountability on all decision on project version FULL_VERSION : display history of decision by user / project / ... MVP : a relational database can be used

Requesting front to klarity back-end

The requesting available for the front will enable interaction with the back-end on order to :

• get data to update front data model,
• manage authentication,
• apply decision by modifying data in the back
• A single request can get data that will be displayed in different view

Infrastructure monitoring constraint

• S3 access performance ( periodic benchmark )
• CPU / RAM / DISK / USAGE (per instance)
  • Peak in the last x days
  • Average usage.
• New client instance creation / deletion ( periodic benchmark)

Access right Management

Access right management in KD relies on the following elements

Design constraint

• For design purpose, the access right management will be provided within an extension.

User authentication

• each user have an ID,
• an authentication process is provided to validate who claim to be user during connection,
• only authenticated user shall access KD content,
• no anonymous access to any content.

Role and capabilities

A capability refers to the right to perform an action: comment, propose, review, decide(validate or reject), force a decision, request a new version... A subcapability refers to right for a specific role to hold a capability at a specific stage (scoping, development or operation)

A metric for instance, can be commented, reviewed and validated or rejected through a decision. Which represents three capabilities. The associated capabilities for a specific metric of a PCIV are defined in the PCIV configuration file and uses the following syntax : prefix_suffix

• prefix designates the nature of the capability, which is used to precisely decide who may hold this capability
• suffix designates the type of capability : comment, review, decide, etc.

Such a capability is identified as a subcapability A role is a set of subcapabilities.

Example

An item holding :

• functional_validate
• functional_review

Can be validated or reviewed , in a specific stage, by any role having this subcapability for this stage of this PCIV

See this diagram class for a more complete vision.

The subcapabilities of a role are defined through a matrix of which the following table is a template :

SubCapability	Scoping	Development	Operation
functional_comment	X	X	X
functional_navigate	X	X	X
functional_review	X	X
technical_propose	X	X
technical_review	X		X
...	X		X

Every role holds a similar table and any user with this role would have the possibility to comment any item having the "project_comment" in its PCIV configuration, whatever the stage. In the same way, this user would be able to review any item having the "requirement_review" subcapability indicated in the PCIV configuration file, as long as the version is in Scoping or Development stage.

1. Roles are assigned per project.
2. A user can have multiple roles.
3. The role interface is impletemend in the common package as function :

check_role_capability(request_capability, active_stage, [avalable_roles]) -> BOOL

Capabilities association to actions

Capabilities are associated to actions through the extension in which the action is defined. This association is described here.

In the PCIV configuration we have a reference to the capability suffix declared in the extension implementation, this reference is associated to a prefix. The association of the prefix and the suffix defines a SubCapability which is a capability that can only be done on the Metric Group it is declared.

This SubCapability will then be used by roles. If a role has this SubCapability in the on-going stage then all users with this role will be able to proceed with the Action initially declared in the extension.

Capabilities association to roles

An item which is configured with, for instance "metric_review" as its capability, is reviewable in a Scoping stage for any user who holds a role which have "metric_review" capability for the Scoping stage.

This association is done through a matrix for each role which contains each subcapability and designates for which stage this subcapability is activated for this role.

More informations here

Table of 10 native roles :

Role	Description
Business Leader
Product Owner
Business Line Manager
End-User
Project Leader
IA Team Leader
System Architect
Software Engineer
System Integrator
Auditor

These roles are static.

MVP : All roles can perform all of the actions defined in actions, therefore they have all the subcapabilities of each project.

FOR ANY ROLE	Scoping	Development	Operation
functional_assignrole	Yes	Yes	Yes
technical_assignrole	Yes	Yes	Yes
legal_assignrole	Yes	Yes	Yes
functional_navigate	Yes	Yes	Yes
technical_navigate	Yes	Yes	Yes
legal_navigate	Yes	Yes	Yes
functional_comment	Yes	Yes	Yes
technical_comment	Yes	Yes	Yes
legal_comment	Yes	Yes	Yes
functional_propose	Yes	Yes	Yes
technical_propose	Yes	Yes	Yes
legal_propose	Yes	Yes	Yes
functional_review	Yes	Yes	Yes
technical_review	Yes	Yes	Yes
legal_review	Yes	Yes	Yes
functional_decide	Yes	Yes	Yes
technical_decide	Yes	Yes	Yes
legal_decide	Yes	Yes	Yes
functional_forcedecision	Yes	Yes	Yes
technical_forcedecision	Yes	Yes	Yes
legal_forcedecision	Yes	Yes	Yes
functional_request	Yes	Yes	Yes
technical_request	Yes	Yes	Yes
legal_request	Yes	Yes	Yes

Roles association to users

Each user has one to multiple role, which grant him the associated SubCapabilities and therefore, actions. This assignment is done through the graphic user interface with a page with user adminitration and role assignment functionalities.